3D Graphics Programming with QuickDraw 3D 1.5.4

Hit Information

When you create a pick object, you specify (in the mask field of a pick data structure) a hit information mask value that indicates the kind of information you want returned about objects in the model. For example, you could use this code to request information about surface normals and the distance from the pick origin:



 
TQ3PickData             myPickData;

myPickData.mask = kQ3PickDetailMaskNormal | 

                        kQ3PickDetailMaskDistance;

Once you've created the hit list, you can obtain information about a particular hit in the list by calling the Q3Pick_GetPickDetailData function. You pass this function a pick object, an index to a hit within the hit list, and the desired pickDetailValue from one of the bit values defined by the TQ3PickDetailMasks data type:



 
typedef enum TQ3PickDetailMasks {

    kQ3PickDetail_None                          = 0,

    kQ3PickDetailMask_PickID                    = 1 << 0,

    kQ3PickDetailMask_Path                      = 1 << 1,

    kQ3PickDetailMask_Object                    = 1 << 2,

    kQ3PickDetailMask_LocalToWorldMatrix        = 1 << 3,

    kQ3PickDetailMask_XYZ                       = 1 << 4,

    kQ3PickDetailMask_Distance                  = 1 << 5,

    kQ3PickDetailMask_Normal                    = 1 << 6,

    kQ3PickDetailMask_ShapePart                 = 1 << 7,

    kQ3PickDetailMask_PickPart                  = 1 << 8,

    kQ3PickDetailMask_UV                        = 1 << 9,

} TQ3PickDetailMasks;



 
typedef unsigned long       TQ3PickDetail;

QuickDraw 3D returns the specified pick detail data. Before using this information you should call Q3Pick_GetPickDetailValidMask to see what information QuickDraw 3D has returned. The values in the mask field of an initial pick data structure and the validMask value returned by this call can differ.

You need to pay attention to what information is returned in part because some kinds of information are not available for some combinations of pick object types and picked object types. For example, you cannot get information about a surface normal for a hit on a point (because points do not have normals). Similarly, you cannot get a distance value for a window-rectangle pick object (because rectangles have no origin from which to measure). Table 2 indicates the kinds of information you can receive about each type of picked object.

QuickDraw 3D can always return information for the pickID , path , object , and localToWorldMatrix data types. As a result, those fields are omitted from Table 2 .

Table 2 Pick geometries and information types supported by view objects
View object	`xyzPoint`	`distance`	`normal`	`shapePart`
Marker
Point	Point Rectangle	Point
Line	Point	Point
Triangle	Point	Point	Point
Polygon	Point	Point	Point
Decomposition	Point	Point	Point
Mesh	Point	Point	Point	Point